feat: record judge scores as gen_ai.evaluation.result - #43

Summary

Judge scores land as a gen_ai.evaluation.result span event (plus mirrored span attributes) on the judge's invoke_agent span, so conversation turn badges can render.

• with_judge_evaluation holds the judge invoke_agent span open until scoring finishes. execute_and_track returns after the handler has already called span.end(), so without the delay the event would be dropped.
• Event attributes: gen_ai.evaluation.name and gen_ai.evaluation.score.value, mirrored as span attributes. score.label is not invented, and only a finite number is recorded.
• Existing track(evaluation_metric_key) behavior is unchanged.
• TELEMETRY-CONTRACT.md section 4a documents the event contract; section 2 lists the mirrored root-span attributes.

Mirrors js-ai-sdk#27. Part of O11Y-1888. Split out of the original combined PR so the two halves could be reviewed apart — the conversation-id half is #42, now merged, so this targets main.

Review follow-ups

• Judge explanation gated on content capture. gen_ai.evaluation.explanation is emitted only when the judge's own handler captures content. ProviderHandler now carries capture_content, set by create_handler alongside provides_for, so the client core can apply the handler's content decision without reaching into its closure. All six handler factories pass it through. Removing it outright would have left the conversation view's badge tooltip and evaluation banner — both of which read this field — permanently blank. The reasoning always reaches the caller in judge_results.
• float(score) replaced with a non-raising finite-number guard. float() was a new raise site sitting ahead of the existing client.track(evaluation_metric_key, …) call, so a judge returning "0.9 (high)" silently killed the metric this PR claims is unchanged — and in run_judge it escaped uncaught, breaking that function's documented "returns None" contract.
• End time frozen at the handler's end() call, so the deferred end no longer stamps release time and inflate the span by the tracking and parsing work in between.
• Detach even if the deferred end raises, so a failing exporter can't leave the judge capture bound in the task's context.

Verified in staging

Real judge AI Config (chriss-test-judge, Anthropic / claude-sonnet-4-5) attached to chriss-test-config with sampling_rate: 1, in default / staging. The judge's invoke_agent span carries:

gen_ai.evaluation.name        = chriss-test-judge
gen_ai.evaluation.score.value = 0.3
gen_ai.evaluation.explanation = <judge reasoning, present because capture is on>
gen_ai.conversation.id        = judge-expl-py-4e7728ff
telemetry.sdk.language        = python

with the explanation present because this run had capture_content on; with capture off it is absent. Both directions verified.

Rendered with the judge-score UI change, pinned via frontend-version=f413f8a22:

https://ld-stg.launchdarkly.com/projects/default/ai-configs/chriss-test-judge/monitoring?env=staging&selected-env=staging&chartTypes=Tokens%2CSatisfaction%2CGenerations%2CTime%20to%20generate%2CError%20rate%2CTime%20to%20first%20token%2CCosts%2CEvaluator%20metrics&related_resource=eyJ0eXBlIjoiY29udmVyc2F0aW9uIiwiY29udmVyc2F0aW9uSWQiOiJqdWRnZS1leHBsLXB5LTRlNzcyOGZmIiwidHJhY2VJZCI6ImI0NzYwYThhYjQ2MmI2YzViOTk0MDQ5NzE4Njk1ODI1IiwidGltZXN0YW1wIjoiMjAyNi0wOC0yMFQyMDo1OToxNC4wNzI1MDhaIiwiY2FuR29CYWNrIjp0cnVlfQ%3D%3D&frontend-version=f413f8a22

Without that frontend pin the score does not render: the conversation view's existing judge readers expect Vega's agent.judge.* shape rather than the semconv gen_ai.evaluation.* emitted here. Tracked in O11Y-1905.

Reviewer notes

The span.end patch is the part worth scrutiny. Nothing breaks today — judges only take the blocking path — but it is the one place the SDK mutates a live span's lifecycle, and span lifecycle is this SDK's worst historical surface. Three reviewers independently suggested the deeper fix: let the judge own its own span rather than mutating a handler-owned one. Deliberately not done here; it's a design decision that deserves its own call.

Found while verifying — not fixed here

Python's BYOC path calls _setup_telemetry(opts.get("sdkKey", "byoc"), …), so a caller who passes a pre-built client via init_client(client=…) without also passing sdkKey gets every span stamped highlight.project_id: "byoc". The ingest cannot resolve that, so all telemetry is silently dropped. TypeScript's BYOC path falls back to process.env.LD_SDK_KEY. Pre-existing and unrelated to this PR; needs its own ticket.

Test plan

• uv run pytest — 1083 pass, 11 skipped
• uv run mypy packages/*/src, ruff check, ruff format --check clean
• Evaluation event lands on the invoke_agent span after the handler has already ended it
• score.label is not invented; non-numeric scores are rejected without raising
• End time reflects the handler's end() call, not release (test fails if the freeze is removed)
• Against staging: judge score on the span, metric track still fires, explanation absent